home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 25
/
Cream of the Crop 25.iso
/
os2
/
srefv12i.zip
/
initfilt.doc
< prev
next >
Wrap
Text File
|
1997-04-19
|
104KB
|
2,671 lines
Optimization hints, configuration information, and other commentaries
on SRE-Filter. 5 Mar 1997.
This file contains several sections discussing various aspects of SRE-Filter.
1) Optimization hints: a discussion of ways of speeding up SRE-Filter
2) Configuration information: a complete description of all the SRE-Filter
intialization parameters: including the more important parameters set
in INITFILT.80, and the more obscure parameters set in SREFILTR.80.
3) Remote vs. local redirection: A discussion of the various methods
SRE-Filter uses to redirect files.
4) A sample site: A short example of how one might use PUBLIC_URLS to
efficiently set up a site.
===========================================
SECTION 1. Performance hints
(a) The use of the server side include cache (SSI-Cache) is highly
recommended. However, for very dynamic documents (such as documents
that contain several INTERPRET and #EXEC keyphrases), it may
be more efficient to suppress caching of these files (you
can use the <!-- CACHE NO --> keyphrase for just such a purpose).
Upgraders note: now that the SSI-cache has been added to SRE-Filter, we
NO LONGER RECOMMEND using the "send in pieces" option
(as set by the DO_SEND_PIECE parameter).
(b) Suppressing incorporation of server side includes (SSIs)
i) If you set SSI_SHTML_ONLY='YES', and name html
documents, that contain SSIs, with a .SHT or .SHTML
extension: SRE-Filter will not attempt to process SSI's
in .HTM or .HTML files. This can save some processing time.
In fact, if you are using GoServe's caching mechanism (see c below),
this can save a lot of processing time!
ii) If you are willing to NOT have SSIs, then set
NO_INCLUDE='YES'
(this saves more processing time, and it also makes
hints (a) and (b.i) totally irrelevant)
(c) Turn on GoServe's cache. This will have no effect on documents
containing server side includes, but can greatly speed up transfer of
other documents (such as .GIF files).
However, if you have imposed any access controls, SRE-Filter will
suppress caching. To get around this, you can use the CACHE permission.
The CACHE permission (in the ACCESS_FILE) instructs GoServe to allow
caching on a request specific basis.
One good use of this CACHE option is to cache .GIF files
that are used as in-line images (and that of themselves
contain no proprietary information or are unlikely to be requested
explicitily). Note that html documents that have been processed for
server side includes will never be cached, regardless of the use of
this CACHE permission.
Use CACHE with care, since cached files are sent to all requesters!
(d) If you never check "access" info, or virtual directories,
set the access_file and virtual_file to " " (or see note e).
Note that the access file can contain (on a SEL-specific basis):
i> access control information,
ii> ssi, ssp, delete, and put permissions,
iii> NO_VIRTUAL, NO_ALIAS, and NO_POSTFILTER permissions
iv> the "always cache flag",
v> and realm information.
Thus, with access_file="":
* these permissions (et al) will equal to " "
* CAUTION: if allow_access="NO" and ACCESS_FILE=' ', then
site access is given only to SUPERUSERS
(e) Use the NO_VIRTUAL, NO_ALIAS, and NO_POSTFILTER "permissions"
in the ACCESS_FILE to suppress unnecessary processing.
(f) If you have a choice, the ACCESS_FILE method is preferable to the
the HTACCESS access control method: HTACCESS it is not
implemented with quite the same attention to efficiency. Or,
use the NO_HTACCESS permission (in your ACCESS_FILE) whenever possible.
(g) If you have some documents that are supposed to be
available to everyone, and these documents do not have server
side includes, set up PUBLIC_URLS entries for them (since public_urls
are cached if possible)
(h) If ...
you are serving only 1 host,
you have many selectors that you can specify with PUBLIC_URLS,
and these "selectors" are to be interpreted "literally" --
with no internal redirection, auto-header creation,
and no server side includes --
then ...
you can greatly improve throughput by using
the SREFQUIK.80 filter instead of SREFILTR.80.
SREFQUIK.80 is small filter that processes these "literal
public_urls" on a single host server (it also recognizes
"cached" returns).
When a "literal public_url" is requested, SREFQUIK does
all the work, saving a great deal of overhead. That is, the
main filter (SREFILTER) is never called!
On the other hand, if the request selector does not match a
"literal public_url", the standard filter is called, with no
loss of capability.
Notes and Cautions:
* Caution #1: Since SREFQUIK adds overhead to requests that are NOT to
"literal public_urls", if you specify few "literal public_urls" the
net effect may be detrimental.
So, when using SREFQUIK, it is important to specify as many
"literal public_urls" as possible.
* Caution #2: If you modify SREFILTR.80 and are using
SREFQUIK as your filter, be aware that the modifications to
SREFILTR.80 will take effect AFTER you stop, then restart, GoServe.
* Caution #3: If you have specified multiple hosts (using the
HOSTS. variables) , SREFQUIK should NOT be used.
* Caution #4: If you use SREFQUIK, "cached" responses (requests
that GoServe was able to satisfy from it's cache) will
not be checked for the NO_POSTFILTER access permission
(SREFQUIK offers a work-around for this problem).
* For a description of "literal public_urls", see the
discussion of the PUBLIC_URLS variables, and see
Section 4 of this document
* For further details on the SREFQUIK "mini-filter", see SREFQUIK.DOC.
(i) Turn on the RECORD_ALL_FILE cache. This is useful ONLY if you
are recording all requests (i.e.; RECORD_OPTION='YES').
Turning on the cache will cause the RECORD_ALL_FILE to be cached
in memory, with disk-writes every 5 minutes. See the description
of RECORD_CACHE_LINES for details.
(j) If you don't need extensive auditing, set WRITE_LOGS=0
(k) It you don't need "dynamic privileges", set CHECK_ADD_PRIVS='NO'.
(l) As an illustrative example; an apppendix at the bottom of
this document contains a discussion of how to use SREFQUIK,
PUBLIC_URLS, etc. to efficiently setup a site with three levels
of security.
=============================
Section 2. Parameter descriptions
The following parameters are in alphabetical order (by name of parameter).
Many of them can be changed by using SRE-Filter's configurator,
especially the "intermediate mode" configurator. However, to changes several of
these parameters, you must "hand-edit" the INITFILT.80 file. In general, the
"hand-edit only" parameters are more obsure, and may never need to be changed.
"Power users" may wish to see section 2a (below) for a discussion of
variables contained in SREFILTR.80 -- these are "doubly obscure"
variables!
Miscellaneous Notes:
* The terms "variable" and "parameter" are used interchangeably.
* In almost all cases the variables (aka parameters) are set to equal
strings, so if you are "hand editing" INITFILT.80, remember to put
single quotes (') around the stuff on the rhs of the = sign.
* When this document mentions "SEL-specific", it really means
"selector specific", where the selector is the slightly modified
middle portion of the request string sent by the client to the server.
For example, if the client requests a URL of:
http://your.server/animals/bear.jpg
her brower will issue a request string of:
GET /animals/bear.jpg http/1.0
and the selector would be
animals/bear.jpg
Notes on Host-specific parameters:
* Almost all of the parameters (that are set in INITFILT.80) may be "host
specific". The several that aren't are:
INTERPRET_TYPES, DISPLAY_ENV, and HOSTS.
* Parameters set in SREFILTR.80 (described in section 2a)
can NOT be host specific (they apply to all hosts).
* To specify a host-specific parameter, you append the "host nickname"
to the parameter name (see the HOSTS. variable for a discussion of
host nicknames).
For example, to set the CHECKLOG variable for the ZOO host,
CHECKLOG.ZOO='NO'
and for all other hosts:
CHECKLOG='ALWAYS'
where this non host-specific value (CHECKLOG='ALWAYS') is the
"generic" value, and will be used for hosts other then the "ZOO" host.
* When a request to a host is recieved, SRE-Filter will attempt
to find the appropriate host-specific parameters. If a given
parameter does not have a host-specific value, the "generic"
(the value of the non host-specific parameter) is almost always
used instead.
The exceptions are: UNALLOWEDIPS., INHOUSEIPS., PUBLIC_URLS.
* For security reasons, for these three (sets of) parameters
the generic (non host-specific) values are NOT used as a default.
The astute reader may notice that the OWNERS variable is not
on this list of "exceptions". In other words, the
"generic" OWNER has SUPERUSER privileges for ALL hosts.
Note on "hand edited" parameters:
* Currently, the "hand-edited" parameters (that can NOT be set with the
intermediate mode configurator) are:
ACCEPT_RANGE ADD_USER_NAME ADD_RESOURCE_NAME ADD_PRIVS_PREFIX
CHECK_ALIAS
DELIM_1.n DELIM_2.n DISPLAY_ENV DO_SEND_PIECE
HTACCESS_FILE INTERPRET_TYPES MAX_POINTDIST NO_INCLUDE
NO_PROCESSING NO_INTERPRET_CODE PREFILTER_NAME POSTFILTER_NAME
USE_STDOUT VERBOSE
************
ACCEPT_RANGE: Return only specified range of the request file
You can instruct SRE-Filter to respond to a "range:" request header. If such a
request header is present, SRE-Filter will extract the "byte
range" information, and return only this portion of the request file.
Primary use:
Adobe Acrobat can use this to request a given page in a long .pdf file.
If accept_range=NO, this processing will not occur -- the entire file will
always be returned.
If accept_range=YES, this processing will occur. Of course, if there is
no range: header, then the entire file is returned.
Accept range is only used when a non-html file is requested.
Example: accept_range='YES'
For more information on "byte range retrieval", see the document:
draft-ieft-http-range-retrieval-00.txt at ds.internic.net.
Note on GoServe and Multi-part sends: GoServe is a bit flaky with
multi-part sends (byte retrieval being a form of multi-part send).
We suggest obtaining GoServe ver 2.50 from:
http://www2.hursley.ibm.com/goserve/
(ACCEPT_RANGE can be host specific)
***********
ACCESS_FAIL_FILE
If a SEL-specific access is not granted to the client, you can
send the ACCESS_FAIL_FILE as a response. ACCESS_FAIL_FILE should
be one of the following values:
-1 : Do NOT send a message or ask for authorization. This is useful
when combined with "dynamic privileges"
0 : Do NOT use an access_fail_file -- just ask for authorization
1 : If a "SEL-specific" access file exists (as set in ALL_FILE.CTL),
use it. Otherwise, ask for authorization
filename.ext : The fully qualified file name to be used when access is denied.
Note that this may be overridden by a "SEL-specific" access-fail
file.
As with the LOGON_FAIL_FILE, when the ACCESS_FAIL_FILE is an HTML document,
server side includes are NOT attempted.
However, for HTML documents a few special substitutions will occur:
<!--#URL--> phrases are substituted with the request selector.
<!--#SERVER--> phrases are substituted with the servername.
<!-- #WEBMASTER --> phrases are substituted with the WEBMASTER variable.
<!-- #MESSAGE --> phrases are substituted with a short description
of the reason for failure
<!-- #LINK --> phrases are substituted with a "forced" URL: which points
back to this resource, and forces an "ask authorization"
if access is denied.
It is HIGHLY recommended that a #LINK be included. Without such an
entry, the client will be unable to enter a new username/password, should
his first entry be misspelled (or if he had previously used a
different username/password for a different resource on the same server).
PROVISO:
In some cases (such as when dynamic privileges are used to control
access to .GIF files), you may want to use an ACCESS_FAIL_FILE that does
not contain a #LINK. Or, set ACCESS_FAIL_FILE=-1 (for
a very terse "Access denied" response).
Notes:
* When set to ACCESS_FAIL_FILE=0, the client will be re-sent
an authorization request.
* If ACCESS_FAIL_FILE=0, SEL-specific failure files are NOT used,
even if one is available.
* The #LINK entry uses a special form of SRE-Filter request selector.
The effect is to force SRE-Filter to request authorization should
the current username/password be incorrect; thereby avoiding an
annoying recursive trap.
(ACCESS_FAIL_FILE can be host-specific)
***********
ADD_USER_NAME: Controls whether a clients "logon name" should be
added to the list of client privileges.
YES: Add logon name to client privilege list
NO: Do not add logon name to client privilege list.
This can be a useful means of personallizing a client's
privilege list (of course, you could always enter his
name in the privilege list explicitly when setting up his
username/password entry).
Example:
ADD_USER_NAME='YES'
Usage Example:
if a username of ACIDER exists, with a client privileges of
HARD SOFT, then if ADD_USER_NAME='YES', an ACIDER client
privilege is added (yielding a client privilege list of
ACIDER HARD SOFT).
Notes:
* For INHOUSEIPS. entries, the "clientname" (the full, dotted, IP name) is
used as the "logon name".
* If you set ADD_USER_NAME=1, you should be careful that the usernames
you assign (in the USERS.IN file) do not conflict with the words used for
privileges. In particular, don't casually give someone a
username of SUPERUSER or INHOUSE.
***********
ADD_RESOURCE_NAME: Controls whether the "action" portion of the request
selector be included as a resource privilege.
YES: Add the action to the resource privilege list
NO: Do not add.
Similar to the ADD_USER_NAME, this can be a useful shortcut
in environments where highly specific access controls are
required.
CAUTION: When ADD_RESOURCE_NAME='YES', unmatched requests
will require clients to have a privilege matching
the "requested resource".
Example: ADD_RESOURCE_NAME='YES'
Notes:
* The "action" portion of a request selector is everything before the
first ? character (if no ? is found, the entire request selector is used).
* If ALLOW_ACCESS='YES', ADD_RESOURCE_NAME has no effect.
************
ADD_PRIVS_PREFIX: Modifies the prefix used to distinguish "dynamic"
client privileges.
As a security measure, when SRE-Filter adds "dynamic" privileges, it will
append the ADD_PRIVS_PREFIX. For example, if ADD_PRIVS_PREVIX='!', and
a <!-- INTERPRET FILE ADDPRIVS.RXX SATURN ,30 --> keyphrase appears
in a requested document, the client will be granted a !SATURN
client-privilege (in this example, for 30 minutes).
The rationale is to prevent unscrupulous individuals, who may have been
granted a limited ability to post documents to "user" sub-directories,
from subverting access control with keyphrases of the form:
<!-- INTERPRET FILE ADDPRIVS.RXX SUPERUSER, 100 -->
If such problems are not likely to occur, you may want to
set ADD_PRIVS_PREFIX=' '
Example:
ADD_PRIVS_PREFIX='!'
(ADD_PRIVS_PREVIX may be host specific)
************
ALLOW_ACCESS : Control access to server resources.
You can check "access privileges" for server resources (files, programs, etc.)
by setting the ALLOW_ACCESS variable.
YES : no access control
INHOUSE : don't check in-house and superusers.
NO : don't check superusers.
Note that checking involves examination of privilege information
on a per-request-selector basis (using the ACCESS_FILE file).
The ACCESS_FILE is also used for:
1) Controlling server side include privileges and server side processing,
on a SEL-specific basis
2) Allowing caching of files that would normally not be cached
(If CHECKLOG<>"YES" or ALLOW_ACCES<>"YES", then caching is
suppressed).
3) Setting the default "realm" of the resource (see the THE_REALM variable)
4) Permitting PUT and DELETE methods to operate
5) Suppressing aliasing, virtual directory lookup, and "post-filtering"
If you do not ever want SRE-Filter to check the access file,
just set access_file=" ". BUT if you do, the above features will not be
available!
Notes:
* The default name of the ACCESS_FILE is ALL_FILE.CTL (in the DATA/
directory of GoServe's "working" directory).
* WARNING: If you set allow_access="NO", and access_file=" ", then
only SUPERUSERS will have access to your site!
(ALLOW_ACCESS can be host specific)
********
AUTO_HEADER. Automatic generation of response headers.
AUTO_HEADER is used to automatically generate response
headers, based on LINK and META HTTP-EQUIV elements in the <HEAD>
section of HTML documents.
3 values are supported:
NO : Do not generate these headers
HEAD : Generate headers for HEAD requests only
ALWAYS : Generate headers for HEAD and GET requests.
Note that this is only relevant for HTML files.
Also, when AUTO_HEADER occurs, the html file is parsed for header information
before server side includes are attempted -- that is, any server side
include in the <HEAD> of a document will NOT appear in the response
headers (but they will appear in the body of the response).
IN OTHER WORDS -- Server Side Includes SHOULD NOT BE USED IN THE
<HEAD> portion of an HTML document (unless you do not intend to
automatically generate response headers)
Example: AUTO_HEADER="HEAD"
Technical note: HTTP purists would disapprove of the use of the "HEAD" value;
since HEAD method requests are "supposed to" return exactly the same
response headers as GET method requests.
(AUTO_HEADER can be host specific)
*********
AUTO_NAME : Resolving requests for directories.
AUTO_NAME is used to deal with non-specific requests that are NOT to the
root (the /) directory.
AUTO_NAME should contain a space delimited list of potential "directory
specific default names".
Several special names are supported:
*.HTM
or *.HTML : means "use the "directory" name, with .HTM or .HTML appended
!CREATE : Create a list of links, one for each file in the directory.
!CREATE* : Same as !CREATE, but include links to subdirectories
Example: AUTO_NAME=" *.HTM INDEX.HTM PAGE.HTM DESCRIBE.HTM !CREATE "
If a request for xxx/yyy/ (with optional ?abc after the final /) is
recieved, then
first, yyy.htm is looked for (in datadir/xxx/yyy)
second, INDEX.HTM (in datadir/xxx/yyy).
Then PAGE.HTM, and then, DESCRIBE.HTM are tried.
If all these fail, !CREATE signals "just display a list of the files
in this directory".
Note that if !CREATE were not included in this list, and
none of the requested files exist, a not_found message is returned.
Similarly, if !CREATE fails (if there is no such directory),
the not_found message is returned (see the description of NOT_FOUND_URL
for details).
Notes:
* AUTO_NAME is NOT used when request is to the root (to /) -- DEFAULT is
used!
* See NOEXT_TYPE for a discussion of how to deal with requests that
have neither an extension or a trailing / (i.e.; xxx/yyy).
* You can put a "pathed" name (using /, relative to the data directory)
This is one means of handling bad requests (but only if the request
ends in a /) -- just put the home page document in the auto_name list,
i.e.; auto_name=" * INDEX.HTM /HOMEPAGE.HTM "
* It is recommended that a !CREATE be placed at the end of the
AUTO_NAME list (since !CREATE is "always a match", assuming the
request points to a valid directory)
Example: AUTO_NAME=" * INDEX.HTM "
(AUTO_NAME can be host specific)
CAUTION: When using AUTO_NAME (and other types of local redirection)
URL resolution by the client's browser may have unexpected consequences.
See the discussion of "local vs remote redirection" at the bottom of
this document for details!
**************
CHECK_ADD_PRIVS: Check for "dynamic privileges"
CHECK_ADD_PRIVS is used to instruct SRE-Filter to check for "additional,
dynamic privileges", and if they exist, add them to the client's "privilege"
list.
CHECK_ADD_PRIVS can take two values;
YES : Check for additional, dynamic privileges
NO: Do NOT check for additional, dynamic
Example:
CHECK_ADD_PRIVS='NO'
Note:
* When CHECK_ADD_PRIVS='YES', an _ADDPRIV.DOC file is created in the
TEMPDATA_DIR directory (typically, \GOSERVE\TEMP).
* See ADDPRIVS.DOC for a detailed discussion of "additional, dynamic"
privileges.
(CHECK_ADD_PRIVS can be host specific)
***************
CHECK_ALIAS: Controls whether alias checking occurs.
SREFILTR can check all requests to see if they are aliases for some
other action.
Uses of aliases include:
* implementation of searchable indices
* "local" redirection -- useful as a means of assigning
proper document names to abbreviations
(say, to convert an request of OVERVU into OVERVIEW.HTM)
* "remote" document redirection -- typically to a different
ip addreess
* transferring non-data directory files
Setting CHECK_ALIAS to --
NO suppresses this alias lookup
YES causes this lookup to be done for all requests
Example: CHECK_alias="YES"
(CHECK_ALIAS can be host specific)
************
CHECKLOG: When and how to check for "logon rights".
"Logon rights" refer to basic site access rights. These may
be used with, or without, SEL-specific access privileges (see ALLOW_ACCESS)
CHECKLOG can take four values:
1) NO -- never check (basic access granted to all clients)
2) YES -- check when default document (either explicitily, or if a /
is requested). Thus, a request for a specific document
does not require logon rights.
3) ALWAYS -- check on every request.
4) INHOUSE -- Only let IN-HOUSE users in.
IN-HOUSE users are determined by occurence of a
INHOUSE in the client's 'privilege list', or
if the client has an IP address listed in the
INHOUSEIPS.n variables.
Note: if ALWAYS or INHOUSE is selected, then GOSERVE will NOT cache GET
requests (the discussion of the ALLOW_ACCESS variable
describes an exception to this through the use of the CACHE
permission)
Example: checklog='NO'
(CHECKLOG can be host specific)
**********
DEFAULT -- The "default" (home) page.
Use this when a default request (say, http://www.joe.com/ ) occurs.
Note: it is traditional, but by no means required,
to use INDEX.HTM as your default
You can also use DEFAULT to redirect a request (using a 301 redirection),
say, for an IP Alias that has moved. To do this, just enter the full
URL -- be SURE to include the leading http://
Examples: default='index.htm'
default.zoo='ourzoo.htm'
default.circus='http://silly.places.net/bigtop.htm'
Note that default.zoo defines the DEFAULT file for requests to the
ZOO host only. Also note that default.circus is redirected.
(DEFAULT can be host specific)
CAUTION: When using DEFAULT (and other types of local redirection)
URL resolution by the client's browser may have unexpected consequences.
See the discussion of "local vs remote redirection" at the bottom of
this document for details!
**********
DIR_EXCLUSION: A list of files and subdirectories that the !DIR
directory lister should exclude.
SRE-Filter's !dir function can be instructed to suppress displaying
certain files and subdirectories. To do this, one uses the
DIR_EXCLUSION parameter. DIR_EXCLUSION should contain a space
delimited list of files and subdirectories".
Example: dir_exclusion='Htaccess. /private describe.txt *.CNT '
Note that a / must preceed subdirectories (otherwise, the entry is
interpreted as a file name).
Notes:
* The !dir function is used by the !CREATE option of AUTO_NAME.
* Subdirectories are assumed to be relative to the "requested directory",
and should only be one name deep. That is, an entry of
/personal/family would be ignored.
* The wildcard character (*) can be used in file and directory names.
* For a further discussion of the !dir function, see DIR.DOC.
(DIR_EXCLUSION can be host specific)
**********
DIR_OPTIONS: Set the display options of the !dir function.
To control the display option of SRE-Filter's !dir function, you should
modify the DIR_OPTIONS parameter. DIR_OPTIONS should contain a
space delimited list of parameters.
The allowed options are:
AUTO_DESCRIBE DESCRIBE DESC_LEN DATEFMT MULTI_SEND
NOSIZE NOTIME NODATE NOICON NOSORT NODIR NO_RECURSE_DIR
SIZEFMT SHOWPARENT TABLE TABLE_BORDER TIMEFMT
For a description of what these options do, see DIR.DOC.
Example: DIR_OPTIONS='notime auto_describe describe datefmt=u '
Notes:
* The !dir function is used by the !CREATE option of AUTO_NAME.
(DIR_OPTIONS can be host specific)
**********
DISPLAY_ENV -- write "SRE-Filter" environment variables to PMPRINTF
Use this as a debugging tool to display the values of the SRE-Filter
enviroment variables in the PMPRINTF window.
DISPLAY_ENV = 1 : The SRE-Filter environment variables (basically,
transforms of everything in INITFILT.80 and REPSTRGS.IN)
are written to the "PMPRINTF" window. This will occur
whenever the environment variables are refreshed
(say, when you change INITFILT.80).
otherwise : Do not write environment variables.
Example
DISPLAY_ENV=0
(DISPLAY_ENV is NOT host specific)
*************
DELIMITERS for KEYPHRASES
SREFILTR does "server side" includes by looking for keyphrases in your
HTML documents. A keyphrase is defined as: delim1 keyword keyvalue delim2.
Delim1 and Delim2 are strings (possibly 1 character) that signal the
location of the keyphrase. These delimiters should be odd,
yet easy to remember (and not likely to occur in your text).
ALTHOUGH WE DO NOT RECOMMEND IT, you can enter several sets of delimiters.
One useful set is the HTML comment delimiters '<!--' and '-->' .
If you use these, the raw document will not look too wierd should it be
accidentally sent to the client "as is").
For each set of delimiters, You MUST specify both the beginning (DELIM_1)
and end (DELIM_2) delimiter.
Examples:
delim_1.1="<!--"
delim_2.1="-->"
delim_1.2="{"
delim_2.2="}"
delim_1.3=0
delim_2.3=0
or, if just the ZOO host should recognize a second set of delimiters
delim_1.1="<!--"
delim_2.1="-->"
delim_1.2=0
delim_2.2=0
delim_1.1.zoo="<!--"
delim_2.1.zoo="-->"
delim_1.2.zoo='{'
delim_2.2.zoo='}'
delim_1.3.zoo=0
delim_2.3.zoo=0
Note: The most important reasons for NOT using several sets of delimiters:
* SSI-Caching will be turned OFF (regardless of value of SSI_CACHE_ON)
* SSI processing will be slower
* DO_SEND_PIECE will be turned OFF
But if you are willing to accept these performance disadvantages,
then the use of several delimiters should cause NO problems.
(DELIMS can be host specific)
*************************
DNS_CHECK: Force DNS check before access
As a security measure, you might want to look up the IP name of the
client (using the client's IP address and his DNS). If no name can
be found, logon is not allowed.
NO: do not check DNS for an IP name
YES: Force lookup of IP name before allowing access
Although this will provide some security agains "fake" IP addresses, it
will also slow down response time. Furthermore, many legitimate clients
may not have "names" (say, if they are using pooled IP addresses).
DNS_CHECK='NO'
(DNS_CHECK can be host specific)
********
DO_SEND_PIECE: Allow SRE-Filter to send "pieces" of a document as they
become available.
NOTE: We no longer recommend enabling the DO_SEND_PIECE parameter -- it
conflicts with the SSI Cache (that is, we recommend DO_SEND_PIECE=0).
To speed up percieved throughput for large documents that contain
server side includes, transferal of earlier portions of the
document "as they become" available is recommended.
DO_SEND_PIECE controls this feature, with values:
NO : Do NOT send "pieces of the document" as they become
available (send the entire document when it's ready)
YES: DO send these pieces.
DO_SEND_PIECE is ignored if there is more then one set of
delimiters, or if FIX_EXPIRE is greater then 0. If either of these
hold, "pieces" will NOT be sent (that is, DO_SEND_PIECE is set to NO).
Example:
DO_SEND_PIECE='NO'
WARNING: If you want to "set header elements" (such as cookies)
by using server side includes (i.e.; by using INTERPRET
keyphrases), then you MUST set DO_SEND_PIECE='NO'
(DO_SEND_PIECE can be host specific)
********
DO_HTACCESS: Controls whether the HTACCESS method is used.
To provide compatability with HTTPD style servers (such as Don Meyer's
GOHTTP), SRE-Filter supports the HTACCESS method of access control
(see the description of HTACCESS_FILE in INITIFLT.DOC for details).
DO_HTACCESS can take two values
YES: Enable support of the HTACCESS access control method
NO: Do NOT support HTACCESS.
Example: DO_HTACCESS='YES'
When DO_HTACCESS='YES', SRE-Filter will check for an HTACCESS file
in the directory (and parent directories) of the requested file.
Note that this control is by "file name", rather then by request selector.
Details on HTACCESS files are in the description of the
HTACCESS_FILE variable.
Details concerning the use of the HTACCESS method can be found at:
http://w3.ag.uiuc.edu/DLM/GoHTTP/htaccess.html
(DO_HTACCESS can be host specific).
*********
FIX_EXPIRE: For fixing the GoServe automatic response header.
For certain responses; when FIX_EXPIRE > 0 , instead of returning
the default GoServe response headers, SRE-Filter will generate it's own.
In particular, it will add FIX_EXPIRE "fractions of a day" to the
current date/time, and use it as the File-Expires date.
FIX_EXPIRE is used whenever a server-side include containing HTML
document is being returned. It is also use by several SRE-Filter
add-ons (such as by GETAFILE and DOSEARCH), and by CGI-BIN programs.
To use it in a custom REXX program, see the description of SREF_FIX_EXPIRE
in SREFPRC1.DOC (SREFPRC1.DOC is available from
http://rpbcam.econ.ag.gov/srefilter/srefprc1.doc).
Note that if FIX_EXPIRE=0, the default GoServe response
headers will be used --plus any headers that may have been specified
using the META and LINK elements in the HEAD (see AUTO_HEADER).
Setting FIX_EXPIRE > 0 can be useful when relatively static (that do not
depend on the current "hour") server side includes are performed.
In such cases, GoServe automatically sets the expiration time to be
the current moment. This can be a hassle for some clients (Netscape
will reload such "expired" documents if "backed up" to).
Note that a value of FIX_EXPIRE=0.1 = .1 * 24 hours = 2.4 hours.
Also note that to use DO_SEND_PIECE, you must set FIX_EXPIRE=0
Example: FIX_EXPIRE=0
(FIX_EXPIRE can be host specific)
Alternative method of suppressing "immediate expire":
* When creating REXX server side programs, you can avoid this
problem by using 'FILE TYPE ... NAME TEMPFILE ' rather then
'FILE ERASE TYPE ... NAME TEMPFILE ' -- the "expire immediately"
response header is NOT added to non 'FILE ERASE' completion codes.
However, you should remember to delete your TEMPFILE (use the
sysfiledelete rexx procedure).
... furthermore, you may want the document to expire in a few hours,
a message FIX_EXPIRE is designed to deliver.
* If you are using GoServe ver 2.50, the HEADER NOTIME option can be used.
SPECIAL OPTION: If you are useing GoServe 2.50, setting
FIX_EXPIRE=1000 will invoke this HEADER NOTIME option.
**********
HEADERS and FOOTERS: Automatically added to all HTML documents.
You can specify a block of HTML code to include at the beginning and the
end of the body of the document. This is done by specifying HEADERS.n
(n=1...) and FOOTERS.n
To suppress this, set HEADERS.1=0 and/or FOOTERS.1=0
Notes:
* HEADERS.n lines are written (consecutively) just after the first
<BODY> phrase in your document (see example 3 below for an exception
to thisrule)
* FOOTERS.n lines are written just before the last </BODY> phrase
in your document.
Examples:
1) Simple case:
HEADERS.1=' <em> Our docuuments are supplied as-is </em> <p>'
FOOTERS.1=' <p> <strong> goodbye </strong> '
2)To suppress headers and footers
HEADERS.1=0
FOOTERS.1=0
3) The "exception":
Headers.1='<BODY bgcolor="#5500aa"> <h1> This is our site! </h1> '
Whenever the HEADERS.1 lines begins with <BODY, then
rather then writing the header AFTER the first <BODY ...> element,
the header will replace the first <BODY ..> element.
HEADERS and FOOTERS can be host specific.
For example:
HEADERS.1.ZOO = ' <B> The ZOO server </b> '
HEADERS1.1.CIRCUS = ' <em> The Circus Site </em>
HEADERS.2.ZOO=0
HEADERS.2.CIRCUS=0
will set up a one-line header for the ZOO and for the CIRCUS "hosts".
*************
HOME_DIR: The "home directory" -- used as a text replacement whenever a ~
is encountered in a request selector.
A typical value of this would be "Users/".
Example: HOME_DIR='USERS/'
(HOME_DIR can be host specific)
ADVANCED OPTION: Specifying User Subdirectories
In many cases, you may wish clients to have access to particular
subdirectories of your "Users" directories. For example, all
"students" may have space on the server machine, some of which
is used for web, and some for "personal" purposes. The goal is to
give clients direct access to the "web" related directories
but not to the "personal" directories.
This can be achieved by including a $ in the HOME_DIR parameter.
Specifically, the $ is replaced by the substring between the ~ and the
first / following the ~.
For example:,
If the HOME_DIR=USERS/$/WWW
and the request selector is /~GERALD/RESUME.HTM
Then SRE-Filter will use:
/USERS/GERALD/WWW/RESUME.HTM
Summarizing, given a $ in the HOME_DIR.
1) SRE-Filter reads the substring (of the request selector) between ~ and
the first / following the ~ (i.e.; GERALD)
2) The substring is deleted from the request selector
3) The $ in the HOME_DIR is replaced with this substring (from step 1)
4) The ~ in the modified request selector (from step 2) is replaced with
the modified HOME_DIR (from step 3)
NOTES:
* If there is no $ in the HOME_DIR, a simple HOME_DIR for ~
replacement is done. For example, if HOME_DIR=USERS/and the
request selector is /~GERALD/RESUME.HTM, the result would be
/USERS/GERALD/RESUME.HTM
* If a / immediately follows the ~ (in the request selector), the $ is
removed from HOME_DIR (without replacement).
* HOME_DIR substitution occurs BEFORE virtual file lookup and AUTO_NAME
construction, but after ALIAS conversion. Thus, the ~ can point to a
virtual directory (or a subdirectory of a virtual directory).
* HOME_DIR for ~ substitution is also used when resolving filenames
requested in server side includes.
* CAUTION: Since HOME_DIR is used in a direct textual substitution, only
a mild degree of syntax checking is attempted. In particular,
// are converted to /. To be safe, be sure your use of ~ is
internally consistent.
**************
HOSTS. : Stem variable containing information on multiple hosts.
The HOSTS. stem variable(s) is used to define the multiple hosts
(IP addresses) your server will recognize.
Each HOSTS. entry should contain the following comma-delimited information:
IP_address, host_nickname, default_dir
Where:
IP_address is the IP address (numeric or character) of the host.
You should use the full name -- do not use a "local
abbreviation" (that is, don't use bill as a shorthand
for bill.my.org; even though your local dns may recognize it)
host_nickname is the "nickname" that you will use to refer to this host.
It MUST NOT be a number -- that is, it must contain
a non-numeric character. Thus, 234 is invalid, but
N234 is okay.
default_directory is the default data directory for this host
Examples:
hosts.1="dh.ag.gov , MY1 , e:\WWW1 "
hosts.2=" 151.122.33.6 , H20 ,e:\www2 "
hosts.3=0
If you do NOT have multiple hosts, set hosts.1=0
Note that we recommend that the last hosts. value = 0.
A Caution on Using IP Aliases: IP aliases offer a convenient means of
setting up multiple hosts (IP names) while only using one numeric ip address.
Unfortunately, use of IP name aliases requires browsers that understand
HTTP/1.1; specifically, that send the HOST: request header with each request.
Although NetScape (2.0+) will do this, most older browsers will not!
In these cases, SRE-Filter will use the numeric IP address (that is, it will
use the "canonical name" for the IP address, rather then the desired alias).
Note: When using multiple hosts, you can specify many of SRE-Filter's
parameters, both here and in the various .IN, .CNT, and .CTL files,
to be "host specific".
For obvious reasons, HOSTS can NEVER be host specific!
****************
HIT_CACHE_LEN and HIT_CACHE_DURATION: Used to limit false hits.
To reduce the number of "false hits" (from clients returning to
your document after a short absence, which is often caused by the
use of a browser's "back" button), a current hits list can be
maintained. If a request matches a request in this list (where
the request selector and the client's IP address are both used),
the "count of hits" will not be augmented. Specifically,
the COUNTER_FILE and the RECORD_ALL_FILE will not be augmented.
There are two methods of storing these current hits: in the
"environment" or in a "file".
1) Environment. It's fast to access, but can not be large (OS/2 has
problems with large environment strings).
To specify this, set HIT_CACHE_LEN to the number of K you wish to set
aside. For example:
HIT_CACHE_LEN=5
(note: each request needs about 50 bytes, more if the request selector
is long. Thus, this example would store approximately
the 100 most recent requests)
2) File. Not as fast, but can contain an indefinite number of hits.
To specify this, set:
HIT_CACHE_LEN='FILE'
A special file in the TEMP/ subdirectory of the GoServe "working"
directory, with the name _HITCACH.80 (or .nnn if nnn is your serverport)
is created and used to store recent hits.
Each selector/client pair will be retained for HIT_CACHE_DURATION minutes.
Note that "overflow" will NOT occur, but the _HITCACH.80 file may
become large. Since "expired" entries are removed, only in rare
circumstances (extremely heavy load, or when HIT_CACHE_DURATION is
very large), will the file size become problemmatic.
To turn of this feature, set HIT_CACHE_LEN=0
Example:
HIT_CACHE_LEN=2
HIT_CACHE_DURATION=5
HIT_CACHE_LEN='FILE'
HIT_CACHE_DURATION=20
Notes:
* Since use of the environment to store large amounts of data can
result in odd effects a limit of 50K on the size of HIT_CACHE_LEN
is imposed. HIT_CACHE_DURATION is limited on the lower end to 1 (minute),
with no limit on the upper end.
* If you are using the FILE mode, a limit of 10,000 entries is imposed.
* HIT_CACHE_LEN and HIT_CACHE_DURATION can NOT be host specific.
*****************
HIT_OWNER_SUPPRESS: Used to suppress hit recording from "OWNERS"
Switch to turn off and on the "suppresion of OWNER request"
HIT_OWNER_SUPPRESS='YES'
Do not record (in the COUNTER_FILE or RECORD_ALL_FILE)
any request from an OWNERS.
HIT_OWNER_SUPPRESS='NO'
Requests from OWNERS are recorded.
This is provided to limit the number of false hits attributable to
site-maintenance operations (say, from the Webmaster monitoring
her own site).
Example:
HIT_OWNER_SUPPRESS='YES'
Note: the HIT_SUPERUSER_SUPPRESS variable (set in srefiltr.80)
can be used to extend the "range" of HIT_OWNER_SUPPRESS to
include SUPERUSERS.
***************
HOME_NAME : The name of your organization
The colloquial (not necessarily IP name) of your organization.
This can be included in a document by using the REPLACE HOME_NAME
keyphrase. Note it's use in NOT_FOUND_URL.
home_name="DIVISION/AGENCY/DEPARTMENT/GOV"
(HOME_NAME can be host specific)
*******
HTACCESS_FILE : The name of the HTACCESS file.
When DO_HTACCESS='YES', SRE-Filter will look in the "requested file's"
directory (and it's parent's directory) for file(s) with the name
given by HTACCESS_FILE. Typically, this is HTACCESS. or .HTACCESS,
but you can use any name you want (but do NOT include path information).
Example: HTACCESS_FILE='HTACCESS.'
(HTACCESS_FILE can be host specific)
Hint: The HTACCESS_FILE contains access control information, as well as
URL redirection and "default index" information. To use the URL
redirection, you should set up a file containing entries of the form:
old_url : new_url
i.e.
PLANET/JUPITER.HTM : http://www.starts.edu/ss/n5.htm
(note the old_url should not contain http://, and should not contain
the dot address)
(HTACCESS_FILE can be host specific)
*******
INHOUSEIPS. : Stem variable containing IP address of "in-house" clients.
You can specify any number of "in-house IP domains".
Just specify the 4 elements --
you can use * for "all" (say * in 111.222.33.*)
If Logon controls are desired, then clients with these
IP addresses are automatically given access (they don't need to
provide a username and password).
In addition, you can specify extra privileges for each inhouseips. entry.
Examples:
inhouseips.1="151.121.64.* VIEWMESS CONTROL "
inhouseips.2="JOE.USDA.GOV "
inhouseips.3=0
(All clients from 151.121.64.xxx are given VIEWMESS and CONTROL
privileges, in addition to the privileges contained in the
INHOUSE_PRIVS variable)
Notes:
* If you do NOT want to identify "in-house" clients, set inhouseips.1=0
* Note that we recommend that the last inhouseips. value = 0.
* INHOUSEIPS. can be host specific.
In fact, non-host specific values of INHOUSEIPS will NOT be used
as "default" values!
For example:
inhouseips.1.candy='MANAGER.STORE.COM CONTROL '
indicates that requests from MANAGER.STORE.COM to the "host"
with a nickname of CANDY should be treated as an "in-House"
request. Note that if no HOSTS. are specified, this entry
will never be used!
*******
INHOUSE. and SUPERUSERS.
The following are special variables used with the INHOUSE.n
and SUPERUSER.n replacement selector (see decripition of the REPLACE
keyphrase). They will be displayed only for
"inhouse" and "superusers", respectively.
Note that INHOUSE.n variables correspond to INHOUSE.n replacement
strings, and SUPERUSER.n variables correspond to SUPERUSER.n
replacement strings.
Examples:
inhouse.1=" (Staff Version) "
inhouse.2=' .. more staff stuff '
superuser.1="(Super User)"
inhouse.3=0
superuser.2=0
We recommend that the last inhouse. and superuser. should equal 0.
Note that inhouse. and superuser. can be host-specific; i.e.:
INHOUSE.1.CANDY='Special this week: Chocolate'
**************
INHOUSE_PRIVS: Privileges for IN-HOUSE clients.
A space delimited list of privileges to be granted to OWNERS and
IN-HOUSE clients. It is HIGHLY recommended that INHOUSE_PRIVS always contain
INHOUSE as one of the privileges!
Example: inhouse_privs=" INHOUSE SECRET1 "
Note that INHOUSE_PRIVS can be host specific.
For example: INHOUSE_PRIVS.ZOO=' INHOUSE SCHEDULES '
********
INTERPRET_TYPES: Associate an extension with a CGI-BIN script processor
SRE-Filter can use "non-REXX" processors to interpert CGI-BIN scripts.
To do this, you must tell SRE-Filter which processor to associate
with a file extension; where the file extension appears on the
"scriptname" (that follows the CGI-BIN/ portion of the request
selector).
This "association" is accomplished with the INTERPRET_TYPES parameter.
INTERPRET_TYPES should be a space delimited string of "type_options".
Each type_option should have the form:
EXT=Interpreter_invocation
For example:
interpret_types=' PL=PERL5 FOO=D:\FAKEIT\FOOEXEC '
The first type_option (PL=PERL5) instructs SRE-Filter to use the PERL5
program to interpret all CGI-BIN scripts with a .PL extension
(this example assumes that PERL5 can be found in the OS/2 PATH).
The second type_option (FOO=D:\FAKEIT\FOOEXEC) instructs SRE-Filter to use
D:\FAKEIT\FOOEXEC to interpret CGI-BIN scripts with .FOO extensions.
Note that a fully qualified name is used for this "FOO interpreter".
Of particular interest is the use of one of the OS/2 PERL interpreters;
since there is a slew of PERL scripts out there. It's not that
hard to obtain a PERL interpreter -- see PERL.DOC for details
on one we've had some success with.
Note: by default, INTERPRET_TYPES=' PL=PERL5 '
(INTERPRET_TYPES can NOT be host specific!)
********
LOGON_FAIL_FILE
If a logon failure occurs (either due to an incorrect username/password,
or due to logon_limit being violated), SRE-Filter can
either send a "401 Unauthorized" response; or the contents of
the LOGON_FAIL_FILE.
If LOGON_FAIL_FILE=0, then a "401 Unauthorized" response is sent.
Otherwise, the LOGON_FAIL_FILE is sent as is; with a few substitutions:
<!--#URL--> phrases are substituted with the request selector.
<!--#SERVER--> phrases are substituted with the servername.
<!-- #WEBMASTER --> phrases are substituted with the WEBMASTER variable.
<!-- #MESSAGE --> phrases are substituted with a short description
of the reason for failure
<!-- #LINK --> phrases are substituted with a link back to this URL.
Notes:
* If the LOGON_FAIL_FILE is unavailable, a "401 Unauthorized" response is
sent.
* When using #LINK, you probably should advice the client to "wait a
minute before trying again" (given that the problem might be
due to logon_limit being exceeded).
(LOGON_FAIL_FILE can be host specific)
*****************
MAX_POINTDIST : Used with the POINT type in mappable images.
Max_pointdist is used with mappable images.
The "point" area is one of the 4 types of areas (circle, rectangles,
polygons, points) used in selecting a URL from a mappable image.
If a selected pixel does not lie in one of the first 3, or does not
lie directly on top of a point; SRE-Filter determines to which (of
the many possible different points that may appear in the map file)
the selected pixel is closest to. However, if the distance to this
closest point is greater then max_pointdist, then the Default URL is used.
Thus, this limits the region of space "potentially assigned" to each point.
Of course, setting max_pointdist to be very high (say, 100000),
will effectively cancel this limit.
Example: max_pointdist=50
(MAX_POINTDIST can be host specific)
*************
NO_PROCESSING: Suppress server side processing
Switch to dictate whether or not to allow server side processing.
YES - Do NOT do allow server side processing
If YES, then requests for server side processing will cause
a 401 Unauthorized message to be returned to the client.
NO - Allow server side processing.
Note: A NO_SSP permission (in the access_file), overrides a NO_PROCESSING='NO'.
Example: no_processing="NO"
(NO_PROCESSING can be host specific)
************
NO_INTERPRET_CODE: Suppress execution of "in-document" executables.
This is similar to NO_PROCESSING, but not as stringent -- it only applies
to the SELECT and INTERPRET CODE "server side include" keyphrases.
YES- Ignore SELECT and INTERPRET CODE server side include keyphrases.
NO - Process SELECT and INTERPRET CODE server side include keyphrases.
Note that NO_PROCESSING (and NO_SSP) have precedence -- if NO_PROCESSING is
on, the value of NO_INTERPRET_CODE is irrelevant.
Notes:
* A NO_CODE permission (in the access_file) overrides a
NO_INTERPRET_CODE='NO'
* CGI-BIN scripts, INTERPRET FILE, and other "executed files" WILL
be processed if NO_INTERPRET_CODE='YES' (assuming NO_PROCESSING, etc.
is not binding).
Hence:If NO_INTERPRET_CODE='YES', you can still use an equivalent
INTERPRET FILE keyphrase.
* The idea is that users of your site will not be able to cause trouble
by including ill-mannered code into their HTML documents.
In other words:
i) If site administrators do not want to review HTML documents
posted on their site (say, by students)
ii) Site adminstrators will review CGI-BIN scripts, etc. that these
"students" wish to place on the server.
iii) Site administrators DO want to grant server side processing
and server side include privileges to clients.
Then, a reasonable level of security, without too harshly limiting
flexibility can be achieved by setting NO_INTERPRET_CODE
(or by judicious use of the NO_CODE permission).
Example: no_interpret_code='NO'
(NO_INTERPRET_CODE can be host specific)
************
NO_INCLUDE: Suppress server side includes.
Switch to dictate whether or not to process server side includes (SSIs).
YES : Do NOT do dynamic page processing.
Files sent as is (if SSI keyphrases occur, they will be sent "as is"
NO : Process server side includes.
If you NEVER include SSI keyphrases, and you want to speed
up processing a bit, set NO_INCLUDE="YES"
Note: A NO_SSI permission (in the access_file), overrides NO_INCLUDE=NO.
Example: no_include="NO"
(NO_INCLUDE can be host specific)
**********
NOEXT_TYPE: Determine how to handle "no extension" request selectors.
NOEXT_TYPE is used to instruct SRE-Filter what to do with requests that
have no extension, do not end in a /, and do not have ? in them. There are
several allowed values of NOEXT_TYPE:
DIR : Interpret as a directory; a / is appended to the end, and
AUTO_NAME is then used.
REDIR : Similar to DIR (a / is appended). However, rather then immediately
using AUTO_NAME; the client is "redirected" back to this new (/ appended)
URL (at which time the AUTO_NAME feature kicks in). This solves
potential "resolution of local URL" problems, at the cost of slower
overall response times. Note that REDIR is the default value.
HTM or HTML : Interpret as an HTML file (a .HTM or .HTML is appended to
the end, respectively)
NONE : Use as is
other_string: Append other_string. For example, if NOEXT_TYPE='.GIF',
then .GIF will be appended to the end).
Example: NOEXT_TYPE="DIR"
(NOEXT_TYPE can be host specific)
CAUTION: When using NOEXT_TYPE (and other types of local redirection)
URL resolution by the client's browser may have unexpected consequences.
See the discussion of "local vs remote redirection" at the bottom of
this document for details!
***************
NOT_FOUND_URL : A message if the requested resource is not found.
This string is sent along with a generic "not found url" response.
Note that it should be a valid HTML string.
Set it to " " if you want no such message sent.
Example: not_found_url='<a href="/"> Visit the HOME_NAME page? </a> '
Note that the HOME_NAME substring will be replaced with the current
value of the HOME_NAME variable.
!!! Special option !!!
If you want to return a custom document, perhaps one that lists
several choices, you should use a special form of NOT_FOUND_URL.
Specifically:
NOT_FOUND_URL= 'FILE=fully_qualified_file_name'
For example:
NOT_FOUND_URL= 'FILE=d:\www\notfound.htm'
If you are very ambitious, you can also append a custom "reponse code".
For example:
NOT_FOUND_URL= 'FILE=d:\www\notfound.htm, 200 Ok with error '
(note the comma follwing the file name)
The returned document will NOT have server side includes -- it is sent
"as is". There are a few special exception to this rule (for HTML
documents):
i) all occurences of <!-- #URL --> will be replaced with the
request selector.
ii) all occurences of <!-- #SERVER --> will be replaced with the
server's IP address.
More notes on the FILE= variant of NOT_FOUND_URL:
* You can specify any type of document (i.e.; an HTML file, a GIF file,
or a plain/text file).
* An fully qualified file is expected: no attempt is made to map a
relative file name to the data directory.
* The file can be anywhere (it need not be in the data directory,
or in virtual directories).
NOT_FOUND_URL can be host specific (and HOME_NAME can also
be host specific).
*********
OPTION_HIT_LINE : Used to write OPTION info instead of counts
OPTION_HIT_LINE is used to write out "# hits drawn from an OPTION
passed to me" -- that is, it used with the REPLACE OPTION_HITS keyphrase
Example: OPTION_Hit_line=":: still access # "
Note: OPTION_HIT_LINE is somewhat obsolete -- it's major purpose is
now better accomplished by using the HIT_CACHE_LEN parameter
(OPTION_HIT_LINE can be host specific)
*************************
OWNERS: Assigned SUPERUSER privileges
Owners are always given SUPERUSER privileges.
You can specify any number of owners, just seperate each of them
with a space. Note that wildcards are NOT allowed. Furthermore,
you must specify an IP address (not an IP name).
If there are no owners, set owners=0.
Example: owners = " 151.121.65.163 "
(OWNERS can be host specific).
************
PRE_FILTER: Call user written pre-filters.
PRE_FILTER is used to control whether a set of user written "pre-filter" is
called before SRE-Filter is given control. It can take 3 values:
NO: Do not call a pre-filter.
YES: Call a pre-filter after checking logon privileges (if the client
does not have logon rights, the pre-filter will not be called)
FIRST: Call a pre-filter as the first action (before checking logon rights)
Note: if the selector matches a public_url, then:
> If PRE_FILTER=FIRST, then the pre filter will be called
> Otherwise, it will NOT be called (that is, PRE_FILTER="YES" is
treated as a NO.)
Example: PRE_FILTER="FIRST"
(PRE_FILTER can be host specific)
************
PREFILTER_NAME: Name(s) of procedure(s) to call as pre-filter(s).
This should point to a list of external procedures (or just to a
single external procedure). Each of them will be called in turn
(or until one of them responds to the client). Note that these
"PREFILTER" files should be in the GoServe working directory.
Examples: PREFILTER_NAME='PREFILTR'
PREFILTER_NAME='PREFILT1.CMD PREFILT9.CMD '
In the first example, note that a .80 (or .nnn if using port nnn) is added to
PREFILTR.
(PREFILTER_NAME can be host specific)
************
POST_FILTER: Call user written post-filters.
POST_FILTER is used to control whether one or more user written
"post-filters " are called before SRE-Filter is given control.
It can take 2 values:
NO: Do not call a post-filter.
YES: Call a pre-filter after sending response to client.
(POST_FILTER can be host specific)
************
POSTFILTER_NAME: A series of procedures to call as post filters.
POSTFILTER_NAME should contain a list (or just one) procedures that
will be called as "post filters".
As with other external procedures, the procedures should correspond
to files with names like POSTF1.80 (they should be in the GoServe
working directory).
If the POSTFILTER_NAME variable is missing, a value of POSTFILT will be used.
Examples: POSTFILTER_NAME='POSTRCRD.80'
POSTFILTER_NAME='POST1.CMD POSTMAIL '
In the second example, first POST1.CMD will be called, and then POSTMAIL --
note that a .80 (or .nnn if using port nnn) is added to a name when there is
no extension (and no final period).
Notes:
* Post-filters are called AFTER the client has recieved a response.
Therefore, post-filters can NOT be used to modify the response.
* Certain GoServe functions are NOT available to post-filter procedures
(see the description of the SAVE_STATE parameter for details).
* POSTFILTER_NAME can be host specific
****************
PUBLIC_URLS. A stem variable containing a list of publicly accessible
server resources.
The basic idea is that before logon or access_controls are checked,
SRE-Filter sees if the request selector matches one of the PUBLIC_URLS.
If so, no logon, etc. checking is attempted. In a sense, the PUBLIC_URLS are
purposely placed outside of the 'protection' of SRE-Filter's various access
controls.
The basic structure of a PUBLC_URLS entry is:
candidate_sel anoption filename
where:
candidate_sel is compared against the request selector
anoption can be: LITERAL LITERAL_NORECORD or NORECORD
filename is a file name (with possible * "wildcard character")
(anoption and filename are both optional)
When the candidate_sel matches the request selector (and the *
wildcard character may be included in the candidate_sel), SRE-Filter
will treat the request as "a request for a Public Resource". Specifically,
when anoption and filename are not specified, this means:
* logon checking does NOT occur
* the ACCESS_file is NOT examined
* local redirections (such as home_name substitution, alias lookup
and virtual directory lookup WILL occur).
* server side includes may be attempted on HTML documents
The anoption and filename option are included to provide further
flexibility.
* If anoption=NORECORD or LITERAL_NORECORD, SRE-Filter will not
record the request, or perform any other "post filter" action
(for example, it will not record this request in the common-log
audit file). This use of NORECORD and LITERAL_NORECORD can help reduce
server load.
* For "literal" PUBLIC_URLS, access permissons are not looked-up.
Thus, if you want to suppress post-filtering you MUST use the
LITERAL_NORECORD variant (see SREFQUIK.DOC for an exception to this).
* If filename is specified (after a LITERAL or a LITERAL_NORECORD),
then filename is used "as is" (the data directory is not used).
Actually, if filename contains a * wildcard, the usual "wildcard
substitution" is attempted. The use of the filename argument
allows a limited form of "aliasing" and "non-data directory file
transfer" (remember: the LITERAL and LITERAL_NORECORD options
suppress both virtual directory lookup and alias checking).
Examples:
PUBLIC_URLS.1='INDEX.HTM'
PUBLIC_URLS.2='MAPS/* '
PUBLIC_URLS.3='STORE/AD1.HTM LITERAL '
PUBLIC_URLS.4='STORE/*.GIF NORECORD '
PUBLIC_URLS.5='PICTURE/HELLO.GIF LITERAL_NORECORD D:\PICTS\HELLO.GIF'
PUBLIC_URLS.6='FAMILY/* LITERAL_NORECORD D:\PERSONAL\*'
PUBLIC_URLS.7=0
The second gives access to everything in the MAPS/ directory (which
might include imagemaps)
The third specifies that STORE/AD1.HTM is to be transfered "as is",
where STORE/ is a subdirectory of the data directory.
The fourth specifies that all .GIF files in STORE/ be transfered,
with no recording of these transfers.
The fifth specifies that PICTURE/HELLO.GIF cause transfer of
d:\picts\hello.gif "as is"; with no "recording" or "post-filtering"
done.
The sixth specifies that all requests beginning with FAMILY/
be directly mapped to D:\PERSONAL\, and transfered "as is", without
recording the request. For example, a request for FAMILY/JUNE.JPG
would result in D:\PERSONAL\JUNE.JPG being transferred.
The seventh, PUBLIC_URLS.7=0, is not required, but is recommended to
avoid possible problems should you change INITFILT.80 "on the fly"
Notes:
* To reiterate, the request selector (sent by the client to your server) is
examined for matches to one of the PUBLIC_URLS. If multiple wildcard
matches (and no exact match) occur, the "best" match is used
The "best match " is defined as the match with the most characters
before the * character; and in the event of ties, the most after.
* The "literal public_urls" are especially useful when you use the
SREFQUIK variant of SRE-Filter to speed up throughput.
* HTACCESS file lookup is suppressed whenever the request matches a
PUBLIC_URLS (HTACCESS access controls, redirection, etc. will not
be attempted).
* In general, all files are assumed to be relative to the data directory
or a virtual directory. Note that for "literal" public_url's,
virtual directories are NOT checked -- so all files are assumed to
be relative to the data directory
Reminder: You can skip the "data directory" lookup by
explicitly naming the file that this PUBLIC_URL maps to.
You can do this simply by adding the (fully qualified) file
name after the LITERAL option.
For example:
PUBLIC_URLS.3='STORE/AD1.HTM LITERAL D:\SHOP\ADS\AD_1.HTM
* If you have no PUBLIC_URLS, set PUBLIC_URLS.1=0
* To illustrate use of PUBLIC_URLS, SRE-Filter is shipped with
PUBLIC_URLS (and an ALIAS_FILE) setup to respond to a
PUBLIC request by listing all files in the PUBFILES/ subdirectory
of the data directory (assuming you've created such a subdirectory).
* If a request matches a PUBLIC_URLS, then:
If PRE_FILTER=FIRST, then the pre filter will be called.
Otherwise, it will NOT be called (that is, PRE_FILTER="YES" is
treated as a NO).
* You can specify PUBLIC_URLS on a host-specific basis.
In fact, non-host specific values of PUBLIC_URLS will
NOT be used as "default" values!
To do this, append a .HOST_NICKNAME to PUBLIC_ULRS. For example:
PUBLIC_URLS.2.ZOO='HOURS.HTM LITERAL'
indicates that this entry applies to requests to the "host"
with a host nickname of ZOO.
CAUTION: When using "literal PUBLIC_URLS with fully qualified file names"
(and other types of local redirection) URL resolution by the client's
browser may have unexpected consequences. See the discussion of
"local vs remote redirection" at the bottom of this document for details!
**************
PUBLIC_PRIVS. Additional privileges for all clients.
A space delimited list of additional privileges to be granted to all
clients).
Set PUBLIC_PRIVS=" " if no additional privileges are needed.
Examples: public_privs=" PUBLIC MESSBOX=*"
public_privs=' PUBLIC MESSBOX=FORUM1 MESSBOX=PUBGRP* '
Notes:
* PUBLIC_PRIVS are used for requests to PUBLIC_URLS.
* The MESSBOX=* privilege (the SRE-Filter default) grants read/write
access to all "message boxes" (assuming Selector and FILE specific
access controls are NOT in place). In contrast, MESSBOX=FORUM1
permits access to the FORUM1 message box. and MESSBOX=PUBGRP*
allows access to PUBGRP01, PUBGRP02, etc.
* The CONTROL privilege allows some of the special (the !xxx) commands.
* The BROADCAST privilege allows the user to "broadcast" e-mail messages
using the SRE-Filter message facility.
* The VIEWMESS privilege allows a client to download a
SRE-Filter message box file (as an alternative to using the
FORUM facility).
(PUBLIC_PRIVS can be host specific)
*******
RECORD_OPTION : Select whether to record all allowed requests.
Used if you want to keep a running total of requests.
RECORD_OPTION can take several values
NO = Do NOT Keep track of requests
YES = Remove argument list, and keep track of all requests.
YES_ALL = Do not remove argument list, and keep track of all requests.
FILE = Record using the name of the requested file (or script)
If RECORD_OPTION is <> NO, results will be written to the RECORD_ALL_FILE.
Example: record_option="YES"
Notes:
* The "argument list" is the ? (and anything that follows it) in a
request selector.
* If you use YES_ALL or FILE, be prepared for your RECORD_ALL_FILE to
grow quite large.
* Note that RECORD_ALL_FILE can be hand-edited. You may want to add
appropriate "wildcarded" entries (such as /TEMP/*) to keep track of
all temporary files, thereby avoiding the creation of
lots of useless entries.
* The RECORD_CACHE_FILE (see section 2a) is used to control caching
of the RECORD_ALL_FILE.
* See the WRITE_LOGS parameters for an alternative auditing mechanism
(the common-log file).
(RECORD_OPTION can be host specific)
************
SMTP_GATEWAY: Domain name of an SMTP server
The SMTP_GATEWAY is used when e-mail messages are to be sent; as may
be attempted by MESSAGE, FORUM, and several other SRE-Filter facilties.
This should be the domain name of a SMTP mail server.
You can use your own server as the SMTP gateway by running SENDMAIL.
Example: SMTP_GATEWAY=MAILBOX.BIG.EDU
(SMTP_GATEWAY can be host specific)
***********
SSI_CACHE_ON
SSI_CACHE_ON is used to enable the server side include cache (SSI-cache).
NO : Turn the SSI-Cache off -- HTML document will not be cached.
YES : Turn the SSI-Cache on.
The SSI-cache is used to store "compiled" versions of HTML documents that
contain server side includes. When a request for such document arrives,
SRE-Filter will return it (perhaps with further modifications).
Turning off caching is sometimes useful in highly dynamic
environments; say, where INCLUDE files are constantly changing.
Example: SSI_CACHE_ON = 'YES'
Notes:
* For further discussion of SSI-caching, please see the SSICACHE.HTM
file.
* The SSI_CACHE_SIZE variable (set in SREFILTR.80) can also be used
to disable the SSI-Cache.
(SSI_CACHE_ON can be host specific)
*******
SSI_SHTML_ONLY: Process server side includes for .SHT or .SHTML files only
SRE-Filter can be instructed to attempt server side includes (SSIs) only on
files with a .SHT or .SHTML extension -- files with .HTM (or .HTML)
extension will NOT be checked for server side includes. This can speed
up file transfer, but does require more care when naming html files.
SSI_SHTML_ONLY : NO. All HTML documents will be checked for SSIs.
Note that files with .HTM .SHT .HTML and .SHTML are
assumed to be html documents (more specifically,
mime type text/html documents).
SSI_SHTML_ONLY : YES Only .SHTM and .SHTML files are checked for SSIs.
Notes:
* SSIs are NOT processed when NO_INCLUDE='NO' (or if there is no
NO_SSI permission).
* The list of "SSI capable" files can be modified to include files with
extensions other then .SHT and .SHTML. See the description of the
SSI_EXTENSIONS variable (in the next section of this document) for details.
REMINDER: SRE-Filter never caches files that contain SSIs (since these
are likely to change on a per request basis).
(SSI_SHTML_ONLY can be host specific)
****************
THE_REALM: "Realm" name to use in requests for username/password.
This is the "realm" which client are "challenged" by --
most browsers will display this "realm" information when asking for
username/password (as when CHECKLOG<>'ALWAYS' and a non-inhouse
client comes a calling)
Example: the_realm="OUR WEB SITE"
Notes:
* Note that the "SEL-specific realm" (specified in the access file) is used
if it's available.
If no "SEL-specific realm" is available, the value of THE_REALM is used.
* THE_REALM can be host specific.
For example: THE_REALM.ZOO='ZOO_SITE'
*******
UNALLOWEDIPS : Stem variable of "disallowed" IP addresses.
You can specify a set of ips that are NOT allowed in (a keep out pests
option). The syntax is the same (* allowed, consecutive numbering), as
the INHOUSEIPS. variables.
Note: UNALLOWEDIPS. is ALWAYS checked (even if checklog=NO) -- and if a
match is found, no logon is requested (they can't get in)
Example: unallowedips.1 = "149.126.12.*"
unallowedips.2="136.12.5.212"
unallowedips.3=0
Example2: unallowedips.1="*.*.*.*"
unallowedips.2=0
Only OWNERS and INHOUSEIPS.n clients can get in !
Example3 : unallowedips.1 = 0
means that no one is automatically excluded.
Notes:
* UNALLOWEDIPS. is checked after INHOUSEIPS. and OWNERS
* We recommend that the last unallowedips. value = 0.
UNALLOWEDIPS. may be specified on a host-specific basis.
In fact, non-host specific values of UNALLOWEDIPS will NOT be used
as "default" values (see INHOUSEIPS. for details)!
********
UPLOAD_MAXSIZE: The maximum size (in Kbytes) allowed in a uploaded file.
Uploaded files are placed on the server when a GET_URL or a PUT_FILE
request selector is recieved.
Set this small (say, 20) if you don't want large files dumped onto
your machine. Set it to 0 to disable all file uploads!
Example: upload_MAXSIZE=50
Note:
Uploads using the PUT http method are not limited by the UPLOAD_MAXSIZE
variable.
(UPLOAD_MAXSIZE can be host specific)
********
UPLOAD_MINFREE: Space that must remain after an upload.
The minimum amount of free space (in Kbytes) that must exist in the
upload_DIRECTORY's hard drive after uploading a file with GET_URL or PUT_FILE.
Set this large (say 100000) if you want to be certain that your
hard drive doesn't get filled up).
Example: upload_MINFREE=25000
Note: if either upload_MINFREE or upload_MAXSIZE are violated, file
upload will not occur.
(UPLOAD_MINFREE can be host specific)
*******
USE_STDOUT: In "INTERPRET" keyphrases, use standard output as a means
of writing results to a document.
If USE_STDOUT='YES', then INTERPRET keyphrases will have two
means of inserting data into your document:
1) If the "INTERPRET" code block contains interpret.results='some string'
2) All QUEUE (and PUSH) statements will be inserted (after the string stored
in interpret.results
If USE_STDOUT='NO', then ONLY step 1 above is used (QUEUE and PUSH commands
will be ignored).
With USE_STDOUT='YES', INTERPRET will work similarly to the #EXEC
server side include -- except SAY generated output is NOT retained
(GoServe seems to trap SAY statements, and sends their output to PMPRINTF).
Hence the need to use QUEUE (or PUSH) ...
Example: USE_STDOUT='YES'
(USE_STDOUT can be host specific)
*******
VERBOSE: Controls the extent of comments written to the Pmprintf window.
Set verbose=1 if you want a fair number of status messages written to
the pmprintf window. Set to verbose= 0, and only error messages and
certain initialization messages will be displayed.
Example: verbose=0
(VERBOSE can be host specific)
Note: for even more comments, set VERBOSE=2, 3 or 4.
*********
WEBMASTER: A static variable.
The WEBMASTER variable is used in certain error and status messages.
Note: you might also want to put specify a CONTACT "REPLACEment variable"
in the repstrgs_file file.
Example: webmaster='<a href="mailto:bb1@farm.ag.gov"> Webmaster </a> '
WEBMASTER may be host specific
(i.e.; WEBMASTER.SWEETSHOP='CANDY@SWEET.ISP.COM')
********
WRITE_LOGS: Enable the common-log, browser, and referer logs.
The WRITE_LOGS variable is used to enable recording of all requests
toe the common-log audit file. In addition, browser and referer information
will be written to seperate log files.
YES = Enable these log files
NO = Do NOT record requestsion in these log files.
Example: WRITE_LOGS='YES'
Note: For further details on the common-log, etc. log files, see
SREFLOGS.DOC.
WRITE_LOGS may be host specific.
********
List of files and directory identifier variables.
NOTE: If you change these, you MUST re-start GOSERVE!
MESSBOX_DIR) Directory containing message boxes,
MAILBOX_DIR) The in-box directory of an SMTP server.
CGI_BIN_DIR) Location of CGI-BIN programs.
TEMPFILE_DIR) Directory to use for creation of "temporary" files
(by external procedures). In comparison to the TEMPDATA_DIR,
this is meant for short-life files (typically created by
a server side program) that are meant to be downloaded
in response to a subsequent request.
Note: The !DELSEND "special action" looks for files in
TEMPFILE_DIR.
UPLOAD_DIR) Default location for uploaded files.
TEMPDATA_DIR) Used for various SRE-Filter temporary files, such as
_HITCACH.80, _ADDPRIV.80, and the $xxx.80 temporary
"response" files. In comparison to the TEMPFILE_DIR, these
are files that are used by SRE-Filter, and are not intended
to be directly accessible to clients.
WORKDATA_DIR) Directory containing various SRE-Filter parameter files.
COUNTER_FILE) "REPLACE HITS" counter file
RECORD_ALL_FILE) "Record all requests" counter file
SENDFILE_FILE) File used by SENDFILE procedure to keep track of requests.
ACCESS_FILE) File used to control access when ALLOW_ACCESS is binding
UPLOAD_LOG) Record of "uploaded files"
ALIAS_FILE) File containing the aliases.
VIRTUAL_FILE) File containing "virtual directory" selector aliases.
REPSTGS_FILE) REPLACEment string file
USERS_FILE) Username/password file
INTERPRET_FILE) File containing blocks of REXX code for use by the
INTERPRET keyphrase (obsolete, retained for backwards compatability).
Examples:
messbox_dir='e:\goserve\MESSAGE'
messbox_dir='c:\mptn\etc\mail'
tempfile_dir='e:\WWW\temp'
upload_dir='E:\goserve\upload'
cgi_bin_dir='E:\goserve\CGI_BIN'
counter_file='e:\goserve\DATA\COUNTER.CNT'
record_all_file='e:\goserve\data\recrdall.cnt'
sendfile_file='e:\goserve\DATA\SENDFILE.CNT'
access_file='e:\goserve\DATA\ALL_FILE.CTL'
tempdata_dir='e:\goserve\temp'
virtual_file='E:\goserve\VIRTUAL.IN'
alias_file='e:\goserve\ALIASES.IN'
repstrgs_file='e:\goserve\REPSTRGS.IN'
user_file='e:\goserve\USERS.IN'
interpret_file='e:\goserve\INTERPET.IN'
Note: The various .CNT, .CTL, and .IN files that are shipped with
SRE-Filter (such as ALL_FILE.CTL) contain additional documentation.
Note that these various filenames are NOT host specific, but
they MAY contain host specific entries!
=============================
Section 2a. Parameters in SREFILTR.80
In addition to the variable contained in INITFILT.80, there are a few
variables in SREFILTR.80 which the ambitious user may wish to change.
Note that NONE of these parameters are host-specfic.
Furthermore, in order for changes to these variables to take effect, you MUST
restart GoServe (this is not strictly true for some of these parameters,
but for safety sake, we recommend restarting GoServe whenever you
change any of these following values).
********
ALWAYS_CHECK_PRIVS
When a request selector matches a "public_URL", SRE-Filter does not
require the client to have "access privileges". However, the
request may be for a SRE-Filter add-on which DOES require specific
privileges.
Setting ALWAYS_CHECK_PRIVS=1 tells SRE-Filter to "get the client
privileges, even if she asked for a public_url". A value of 0
tells SRE-Filter to NOT lookup client privileges when PUBLIC_URLs
are requested.
Basically, If you know that public_urls NEVER require privilege
information, setting ALWAYS_CHECK_PRIVS=0 will improve performance.
If you aren't sure, the safe choice is to set ALWAYS_CHECK_PRIVS=1.
Example: always_check_privs=1
********
BACKUPSERVERLIST and LOADTHRESHOLD
These variables are used to control "load balancing". When load balancing
is active, the server will first check the number of active clients.
If this exceeds the number specified in LOADTHRESHOLD, then the
client is redirected to one of the server's listed in BACKUPSERVERLIST.
LOADTHRESHOLD :
If LOADTHRESHOLD=0, then this "load balancing" is not attempted.
Otherwise, load balancing will occur if the number of active clients
is greater then the value given.
BACKUPSERVERLIST:
If BACKUPSERVERLIST=' ', then load balancing is not attempted.
Otherwise, it should contain a list of IP addresses of alternate
(backup) servers (that presumably mirror the main site).
If BACKUPSERVERLIST contains more then one entry (entries should be
seperated by spaces), then a partially random method is used to select
which server to redirect the client to. For example:
2 entries = 2/3 of the redirections go to the first entry.
3 entries = 1/2 go to the first entry (1/4 to 2nd and 3rd)
Examples:
loadthreshold=0
backupserverlist=' '
loadthreshold=6
backupserverlist='www2.oursite.net'
loadthreshold=3
backupserverlist='www2.oursite.net overflow.hersite.net '
Citation: The basic idea is borrowed from Don Meyer's HTTP filter.
**********
CERN_ISMAP
The value(s) in the spaced delimited CERN_ISMAP variables are used
to indicate that this "is an image-map request". You can specify several
different values (though you should only use one of them in your "image map"
URL).
When one of these identifier-strings appear in a request selector,
SRE-Filter assumes that the request "is a response from a mappable image"
For example, if CERN_ISMAP='/MAPCERN', then selectors (that are generated
by clicking on a mappable image) of the form:
/MAPCERN/GIFSDIR/USMAP.MAP?123,312
will be interpreted as ...
pixel 123,312, in combination with the instructions contained
in /GISDIR/USMAP.MAP, is used to determine which URL to redirect
the client to (where USMAP.MAP is a CERN style MAP file)
IMPORTANT NOTE: the MAPCERN/ is NOT considered to be part of the directory name --
it is treated as a flag!
Example:
CERN_ISMAP="MAPCERN/ CGI-BIG/HTIMAGE/"
Notes
* The trailing / in the above example(s) is optional.
* The "map file location" is interpreted using the regular sre-filter rules (relative to
the GoServe data directory, or to a virtual directory)
* For NCSA style image maps, see the NCSA_ISMAP variable.
* CERN_ISMAP and NCSA_ISMAP replace the ISMAP_URL variable (found in
pre 1.2i.325 versions of SRE-Filter).
********
DELAY_SECONDS
Delay_seconds controls how frequently SRE-Filter
checks input files for updates. Larger values mean more time between
checks. If you never change initialization parameters, etc. you can
set this to a high value (say, 1000) to reduce the load on the server.
Example:
delay_seconds=9
**********
DIR_CACHE_DURATION
DIR_CACHE_DURATION is used by SRE-Filter's !DIR facility. It is the lifespan
(in days, or fractional days) of entries in the "directory listing cache".
Example: DIR_CACHE_DURATION=3
**********
DIR_CACHE_SIZE
DIR_CACHE_DURATION is used by SRE-Filter's !DIR facility. It is the
maximum size (in Kbytes), of the "directory listing cache".
Example: DIR_CACHE_SIZE=1000
Notes:
* setting DIR_CACHE_SIZE=0 will suppress use of the directory listing
cache.
* directory listing "cache files" are stored in the TEMPDATA_DIR, with
names of _nnnnn.DSH (i.e.; _0000012.DSH). There is also a
_DIRLIST.IDX file used as an index to these listings).
**********
HIT_SUPERUSER_SUPPRESS
If HIT_OWNER_SUPPRESS is enabled (see description above), then
"OWNERS" will not have their hits recorded (in the RECORD_ALL_FILE
and in the hit counter file).
You can extend the "range" of HIT_SUPERUSER_SUPPRESS to include SUPERUSERs by
setting HIT_SUPERUSER_SUPPRESS=1. That is, if HIT_OWNER_SUPPRESS=1 and
HIT_SUPERUSER_SUPPRESS=1, the request from OWNERS and from SUPERUSERs
will NOT be recorded.
Otherwise (if HIT_SUPERUSER_SUPPRESS=0), SUPERUSER requests will
be recorded.
Example:
HIT_SUPERUSER_SUPPRESS=1 (the default is 0)
Note: if HIT_OWNER_SUPPRESS=0, then HIT_SUPERUSER_SUPPRESS is ignored
(that is, SUPERUSER requests will be recorded).
**********
NCSA_ISMAP
The value(s) in the spaced delimited NCSA_ISMAP variables are used
to indicate that this "is an image-map request". You can specify several
different values (though you should only use one of them in your "image map"
URL).
When one of these identifier-strings appear in a request selector,
SRE-Filter assumes that the request "is a response from a mappable image"
For example, if NCSA_ISMAP='/MAPIMAGE', then selectors (that are generated
by clicking on a mappable image) of the form:
/MAPIMAGE/GIFSDIR/USMAP.MAP?123,312
will be interpreted as ...
pixel 123,312, in combination with the instructions contained
in /GISDIR/USMAP.MAP, is used to determine which URL to redirect
the client to (where USMAP.MAP is an NCSA style MAP file)
IMPORTANT NOTE: the MAPIMAGE/ is NOT considered to be part of the directory name --
it is treated as a flag!
Example:
NCSA_ISMAP="MAPIMAGE/ CGI-BIG/MAPIMAGE"
Notes
* The trailing / in the above example(s) is optional.
* The "map file location" is interpreted using the regular sre-filter rules (relative to
the GoServe data directory, or to a virtual directory)
* For CERN style image maps, see the CERN_ISMAP variable.
* CERN_ISMAP and NCSA_ISMAP replace the ISMAP_URL variable (found in
pre 1.2i.325 versions of SRE-Filter).
*********
KEY_PREFACE
If the REPLACE, INCLUDE, OPTIONS, INTERPRET and SELECT "keywords"
appear at the beginning of real comments (and you are using the
default "server side keyphrase" delimiters of <!-- and -->), you
might want to add a "preface" to these keywords. For example,
you can add the ! character, so that SRE-Filter will look for
!REPLACE, !INCLUDE, etc.
Note that KEY_PREFACE=0 or KEY_PREFACE='' means "do not add a preface".
Also note that the # can not be used as a preface (since it is
used by the HTTPD-style #INCLUDE keyphrase).
Examples:
KEY_PREFACE='!'
KEY_PREFACE=0
********
LOGON_LIMIT
As a security measure, SRE-Filter's "authorization facility" can limit
the number of unsuccessful attempts, per IP address per minute. When this
limit is exceeded, for the next minute further attempts (from this IP address
will be immediately denied.
To enable this, set LOGON_LIMIT to the number of logon attempts per minute.
A value of 0 means "no limits".
Examples:
LOGON_LIMIT=0
LOGON_LIMIT=3
Warning: do NOT use LOGON_LIMIT=1 (it causes odd problems)
Note: the authorization facility handles all client answers to
"401 Unauthorized" server responses. These include "logon" requests
and "SEL-specific" access requests.
********
MESSAGE_SCRAMBLE
MESSAGE_SCRAMBLE is used to "encrypt" message-box passwords.
You can change it for a wee bit extra security (though security is never going
to be great).
Example:
message_scramble=12415
( message_scramble should be an integer less than 1 million and greater
then 0).
WARNING: If you change this, existing "message" passwords will not be
decodable! That is, they won't work anymore.
Note: only the password, which is just used to control deletion rights,
is encrypted.
***********
NO_NO_RECORD
The NO_NO_RECORD option can be used to suppress the !NORECORD directive.
One reason to suppress !NORECORD is to prevent tricky clients
from sneaking by your audit mechanisms.
To disable the !NORECORD directive, set NO_NO_RECORD=1
To enable it, set NO_NO_RECORD=0
***********
RECORD_CACHE_LINES:
This controls the size of the "request recorder" cache.
Shrinking the size of this cache (say, if you don't have
many documents) will free up memory. Increasing it (say, you
have a large site, and a lot of RAM) will speed up request
recording. In addition, since the RECORD_ALL_FILE is backed up and
then reset when the cache grows beyond RECORD_CACHE_LINES, a larger
cache may reduce fragmentation of these RECORD_ALL_FILE audit files.
To suppress caching, set RECORD_CACHE_LINES=0
Example:
RECORD_CACHE_LINES=750
***********
SAVE_STATE:
SRE-Filter can save some "request specific" state-information:
such as the "selector", the client's address, and the request headers.
This information will be written to a temporary file.
It is then relatively easy to access this information
by using SRE-Filter's SREF_READ_STATE macrospace procedure.
The most important use of this is by post-filter routines -- oftentimes
a necessity, given that GoServe will CRASH if EXTRACT (and other GoServe)
functions are called from a post-filter procedure.
Notes:
* The SREF_READ_STATE SRE-Filter macrospace procedure is designed to use the
output generated by SAVE_STATE. SREF_READ_STATE can be called from
an external procedure, or by a post-filter procedure, using the
following syntax:
info=sref_read_state(state_var,occurence,thread,thread_cache_file)
where state_var can be one of:
SEL REQUEST SOURCE THREAD DATE_TIME SERVER_NAME PRIVSET
CLIENT CLIENT_NAME CLIENT_PORT SERVER SERVER_PORT TRANSACTION
or state_var can be one of the "request header" variables.
* For more details, see the description of SREF_READ_STATE in
SREFPRC1.DOC (SREFPRC1.DOC is available from:
http://rpbcam.econ.ag.gov/srefilter/srefprc1.doc).
************
SEM_MAXWAIT
The "independent threads" that help SRE-Filter work by waiting on
queues. The waiting is partially contolled by a semaphores, which are
set whenever anything is written to a queue. Since OS/2 can be a mite
slow about writing semaphores, it is sometimes convenient to check
the queue, and then go back to waiting if nothing is there.
To increase the frequency that this "check queue even though the semaphore
hasn't been set" occurs, select a low value of SEM_MAXWAIT. Note that
SEM_MAXWAIT is in milliseconds, so values under 100 are considered low.
A possible drawback is that the smaller SEM_MAXWAIT is, the more
SRE-Filter will engage in useless queue examinations. The best value to
use should be determined by experimentation.
Example: SEM_MAXWAIT=15000
*********
SSI_EXTENSIONS: File extensions that are equivalent to SHTML.
The SSI_EXTENSIONS variable contains a space delimited list of file extensions
that will be treated as "SHTML" files. That is, when SSI_SHTML_ONLY='YES',
only files with one of with these extensions will have server side
includes added.
If you add to this list, you may also need to specify that the file has a
text/html MIME type. To do this, you should add entries to the MEDIATYP.RXX
file located in the GoServe directory.
Note: SRE-Filter's default value of ssi_extensions is:
ssi_extensions=' SHT SHTML HTML-SSI HTM-SSI '
****************
SSI_CACHE_SIZE
SSI_CACHE_SIZE is used to set the size of the "server side include cache".
You should enter the size in Kilobytes. For example:
SSI_CACHE_SIZE=5000 (the default)
corresponds to a cache size of 5M.
Notes:
* For further discussion of SSI-caching, please see the SSICACHE.HTM
file.
* Cached files are stored in your TEMPDATA_DIR directory (typically,
GOSERVE\TEMP). They have names of _CSH????.80 (or .nnn, if you are
using port .nnn).
* Once the size of the cached files exceeds this amount, the oldest
entries will be deleted (where oldest is measured in terms of
"last request").
* Setting SSI_CACHE_SIZE=0 will turn the SSI-Cache off (regardless of
the value of SSI_CACHE_ON).
****************
SSI_CACHE_DURATION
SSI_CACHE_DURATION is used to set (in days) the "lifespan"
of entries in the server side include cache.
After this lifespan has been exceeded, the entry will die.
This helps ensure that documents do not get "too far" out of
date (thus, egregious out-of-sync errors won't last forever).
Examples:
SSI_CACHE_DURATION=0.5 -- a 12 hr. lifespan.
SSI_CACHE_DURATION=30 -- a 30 day lifespan
SSI_CACHE_DURATION=0 -- infinite lifespan
Note:
You can use the <!-- CACHE DURATION m.n --> SSI keyphrase
to override this "default" value on a file-by-file basis.
****************
SSI_CACHE_STAMP
The SSI_CACHE_STAMP dictates which fields to use when determining
whether a SSI-cache "trigger" file has changed. SSI_CACHE_DURATION
can have one of the following values:
ALL -- Use time,date, and size (if any change, the trigger is considered
to be out-of-sync)
DATE -- Just use the date
TIME -- Just use the time (hr/minute)
DATETIME -- Use the time and date
SIZE -- Just use the size
Note:
You can use the <!-- CACHE TRIGGER_TYPE stamp --> SSI keyphrase,
where stamp is one of the above values, to override this "default"
value on a file-by-file basis.
========================================
Section 3. A Comparison of Local vs. Remote Redirection of URL's
One of the strengths of SRE-Filter is the variety of redirection
mechanisms it offers, where redirection implies "sending the client
a file that is not a direct mapping of the request selector". Redirection
has two general classes: remote and local.
"Remote" redirection, which is what most of the literature simply
calls redirection, involves telling the client's browser that
"the url you have requested has been moved to xxxx", where xxxx may
be any URL -- it need not be on the same server, and it need not have
the same name.
For example, an alias (in the alias-file) of
whatgot http://www.mine.org/dir1/index1.htm
would cause the server to send back a "302" response to the client's
browser whenever a request for "whatgot" arrives. This 302 response,
would instruct the client's browser to automatically request
http://www.mine.org/dir1/index1.htm.
"Local" redirection is handled solely by the server, and involves
substituting the "request selector" with another "request selector".
SRE-Filter has a number of methods of specifying "local redirection",
such as the DEFAULT, AUTO_NAME, NOEXT_TYPE variables, and the
use of aliases of the form:
whatgot dir1/index.htm.
In all these cases, the browser assumes that the document it recieves
is a direct result of the original request selector issued.
While offering a real convenience, with less demands on the client,
local redirection can have undesired effects. In particular, "partial URLS"
in documents that were sent as the result of a local alias
may not work properly.
A short discussion of how browsers handle partial URLs is germane:
When a link that is specified as a "partial URL"
(such as <img src="wow.gif"> or <a href="wow.htm">)
appears in one of the html documents on your site,the URL actually
requested by the browser is determined by using the "full" URL that
invoked this html document (that contains this partial URL).
For example, if the client asks for, and recieves:
http://www.mine.net/dir1/index.htm,
and index.htm contains a "partial URL" of:
<img src="wow.gif">,
the client's browser would then try to get:
http://www.mine.net/dir1/wow.gif.
In other words, when the browser is asked to get a partial url (that does NOT
begin with a /), it will take everything before the last / in the "parent" URL
(of the document that contains this partial URL) and then append the requested
partial URL.
(Actually, if a URL does not begin with http://, it will
append the "begins with / partial URL" to the http://.../ component of
the "full URL".)
The use of the "local redirection" features of SRE-Filter is
complicated by this "automatic resolution of partial URLS".
For example, if the client requests:
http://www.mine.net/dir1
and SRE-Filter's auto-naming feature converts requested URL's
(abstracting from the http://www.mine.net/ component) of
dir1
to
/dir1/index.htm,
and then sends /dir1/index.htm ... the browser has no way of knowing
this -- that is, the client's browser will assume the server
sent a file named :
dir1
that was located in the
"root of www.mine.net".
So, the browser would assume that a link (in this document) to
wow.gif
is also located in the root (of www.mine.net), and would request
http://www.mine.net/wow.gif
(which is wrong, it should request http://www.mine.net/dir/wow.gif)
So, if you want to use local redirection (AUTO_NAME, aliases, etc.) you should:
1) fully specify the links in your documents ..
i.e.; use /dir1/foo.gif instead of foo.gif
2) Use a <base> element in the <HEAD> of each document...
i.e.; <base href="/dir1/">
3) Tell people to end "non file requests" with a "/" ...
i.e.; tell people to use "dir1/" rather then "dir1"
4) Don't use local redirection (just use remote redirection). This
entails the use of "remote" aliases instead of AUTO_NAME, DEFAULT,
and NOEXT_TYPE.
5) Set NOEXT_TYPE='REDIR'
None of these are great solutions. We might add a
"automatically add the appropriate <base> element to the <HEAD>
of all HTML documents"
feature to SRE-Filter in the future???
....But, since many browsers don't seem to understand the <BASE> element
(WEB ex 1.11d does, but I'm not sure about others)...
========================================
Section 3a. An example of local redirection.
Local redirection, despite it's potential pitfalls, does provide some fairly
powerful configuration possibilitles. As an example, consider recording
"successful" transfers of one of several files: STUFF.ZIP and OTHRSTUF.ZIP.
i) The simple method.
Assume an HTML document with the following links
<A href="stuff.zip">Get our stuff </a> <br>
or, <A href="othrstuf.zip">get our other stuff </a>
Also assume that RECORD_OPTION='YES'
When a client invokes one of these links, SRE-Filter will augment the
appropriate entry in the RECORD_ALL_FILE.
If you wish to record "each individual" request, you could wade through
SRE-Filter's "common-log" audit file. A better idea is to use SENDFILE with
the COUNTER option:
ii) Using SENDFILE, the above would be:
<A href="sendfile?stuff.zip&counter=file=stuff">Get our stuff </a>
<br> or, <A href="sendfile?othrstuf.zip&counter=file=othrstuf">
get our other stuff </a>
The SENDFILE facility is used to transfer the document; and upon
successful transfer, the appropriate .CNT file is updated.
One nice feature of SENDFILE is that unsuccessful (or aborted) transfers
are explicitily noted. There is a minor problem: many browsers
(i.e.; Netscape) will give the client a default filename of "SENDFILE".
This will probably confuse a number of folks.
Fortunately, it's not hard to avoid this problem by using local redirection.
iii) Using local redirection, we use what looks like a standard URL, with
the following in the HTML document:
<A href="stuff.zip">Get our stuff </a> <br>
<A href="othrstuf.zip"> or, get our other stuff </a>
In addition, we include the following entries in the ALIAS_FILE:
stuff.zip sendfile?stuff.zip&counter=file=stuff
othrstuf.zip sendfile?othrstuf.zip&counter=file=othrstuf
When a request for "stuff.zip" arrives, SRE-Filter uses the
sendfile?stuff.zip&counter=file=stuff alias. The client's browser
doesn't know this, and will assume the file's name is stuff.zip
(which is the desired assumption).
This use of aliases could not be replicated with virtual directories, or with
remote redirection!
========================================
Section 4. A Simple Example of using PUBLIC_URLS to set up a site
This section discusses how one might efficiently design a web site with
three levels of security:
1)Open, unmonitored access
2)Open, monitored access
3)Controlled access.
When using SRE-Filter, the best strategy for increasing throughput is to
make extensive use of PUBLIC_URLS, and to use the SREFQUIK version of
SRE-Filter. More precisely, one should liberally specify "literal"
PUBLIC_URLS. With this in mind, consider the following PUBLIC_URLS:
PUBLIC_URLS.1='~/* LITERAL_NORECORD'
PUBLIC_URLS.2='~/*.SHTML NORECORD ' (or, ~/*.SHT if you are using FAT)
PUBLIC_URLS.3='PUBLIC/*.HTM LITERAL'
PUBLIC_URLS.4='PUBLIC/*.SHTML'
PUBLIC_URLS.5='PUBLIC/*.GIF LITERAL_NORECORD'
PUBLIC_URLS.6='HELLO LITERAL D:\WWW\INDEX.HTM'
PUBLIC_URLS.7='STAFF/* LITERAL D:\WWW\PEOPLE\STAFF\*'
PUBLIC_URLS.8-'STAFF/*.SHTML '
public_urls.9=0
the following parameter settings:
SSI_SHTML_ONLY='YES'
HOME_DIR='STUDENTS/PERSONAL'
and the following entry in the ALIAS_FILE:
STAFF/*.SHTML PEOPLE/STAFF/*.SHTML
PUBLIC_URLS.1 and .2 deal with documents available to the "open, unmonitored"
class of requests (i.e.; requests to student owned subdirectories under
the STUDENTS/PERSONAL directory of the data directory). The LITERAL_NORECORD
in .1 instructs SRE-Filter to map the request selector directly to the
~ sub-directory, and to suppress SRE-Filter auditing. The NORECORD in .2 only
suppresses SRE-Filter auditing -- since LITERAL supresses server side
includes, we do not want to use LITERAL_NORECORD to suppress audit file
update.
The third and fourth entries, which deal with the "open, monitored access"
class of requests, are equivalent to the first two -- except SRE-Filter
auditing is not suppressed. The fifth entry suppresses auditing for .GIF
files located in the PUBLIC subdirectory, which we may assume are relatively
unimportant to keep track of.
The sixth entry is equivalent to an "alias", with easy to remember
request selector mapped to a specific file.
The seventh and eighth entries are similar to the fourth and fifth.
URLs that begin with "STAFF/" (but that do not end in .SHTML) will
refer to files in or under D:\WWW\PEOPLE\STAFF. In contrast, selectors
that begin with STAFF, and end with .SHTML, are interpreted using the usual
SRE-Filter rules (i.e.; in the data directory or a virtual directory).
Also note that all requests to STAFF/* will be recorded (including .GIF files).
Lastly, requests that do NOT match these PUBLIC_URLS will be passed
through to SREFILTR.80, and will be subject to the whatever access
controls (and aliasing) have been specified. In other words, the
"controlled access" requests are the default!
Note: "suppression of SRE-Filter auditing" does NOT suppress additions
to GoServe's GOAUDIT.80 file. It does suppress changes to SRE-Filter's
RECORD_ALL_FILE
--- End of Document.